<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>numpy.i: a SWIG Interface File for NumPy &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>
    <script type="text/javascript" src="../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../about.html" >
    <link rel="index" title="Index" href="../genindex.html" >
    <link rel="search" title="Search" href="../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../index.html" >
    <link rel="up" title="NumPy and SWIG" href="swig.html" >
    <link rel="next" title="Testing the numpy.i Typemaps" href="swig.testing.html" >
    <link rel="prev" title="NumPy and SWIG" href="swig.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../index.html">
      <img border=0 alt="NumPy" src="../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="index.html" >NumPy Reference</a></li>
          <li class="active"><a href="swig.html" accesskey="U">NumPy and SWIG</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="swig.testing.html" title="Testing the numpy.i Typemaps"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="swig.html" title="NumPy and SWIG"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../contents.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">numpy.i: a SWIG Interface File for NumPy</a><ul>
<li><a class="reference internal" href="#introduction">Introduction</a></li>
<li><a class="reference internal" href="#using-numpy-i">Using numpy.i</a></li>
<li><a class="reference internal" href="#available-typemaps">Available Typemaps</a><ul>
<li><a class="reference internal" href="#input-arrays">Input Arrays</a></li>
<li><a class="reference internal" href="#in-place-arrays">In-Place Arrays</a></li>
<li><a class="reference internal" href="#argout-arrays">Argout Arrays</a></li>
<li><a class="reference internal" href="#argout-view-arrays">Argout View Arrays</a></li>
<li><a class="reference internal" href="#memory-managed-argout-view-arrays">Memory Managed Argout View Arrays</a></li>
<li><a class="reference internal" href="#output-arrays">Output Arrays</a></li>
<li><a class="reference internal" href="#other-common-types-bool">Other Common Types: bool</a></li>
<li><a class="reference internal" href="#other-common-types-complex">Other Common Types: complex</a></li>
</ul>
</li>
<li><a class="reference internal" href="#numpy-array-scalars-and-swig">NumPy Array Scalars and SWIG</a><ul>
<li><a class="reference internal" href="#why-is-there-a-second-file">Why is There a Second File?</a></li>
</ul>
</li>
<li><a class="reference internal" href="#helper-functions">Helper Functions</a><ul>
<li><a class="reference internal" href="#macros">Macros</a></li>
<li><a class="reference internal" href="#routines">Routines</a></li>
</ul>
</li>
<li><a class="reference internal" href="#beyond-the-provided-typemaps">Beyond the Provided Typemaps</a><ul>
<li><a class="reference internal" href="#a-common-example">A Common Example</a></li>
<li><a class="reference internal" href="#other-situations">Other Situations</a></li>
<li><a class="reference internal" href="#a-final-note">A Final Note</a></li>
</ul>
</li>
<li><a class="reference internal" href="#summary">Summary</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="swig.html"
                        title="previous chapter">NumPy and SWIG</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="swig.testing.html"
                        title="next chapter">Testing the numpy.i Typemaps</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <div class="section" id="numpy-i-a-swig-interface-file-for-numpy">
<h1>numpy.i: a SWIG Interface File for NumPy<a class="headerlink" href="#numpy-i-a-swig-interface-file-for-numpy" title="Permalink to this headline">¶</a></h1>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>The Simple Wrapper and Interface Generator (or <a class="reference external" href="http://www.swig.org">SWIG</a>) is a powerful tool for generating wrapper
code for interfacing to a wide variety of scripting languages.
<a class="reference external" href="http://www.swig.org">SWIG</a> can parse header files, and using only the code prototypes,
create an interface to the target language.  But <a class="reference external" href="http://www.swig.org">SWIG</a> is not
omnipotent.  For example, it cannot know from the prototype:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">double</span> <span class="n">rms</span><span class="p">(</span><span class="n">double</span><span class="o">*</span> <span class="n">seq</span><span class="p">,</span> <span class="nb">int</span> <span class="n">n</span><span class="p">);</span>
</pre></div>
</div>
<p>what exactly <code class="docutils literal notranslate"><span class="pre">seq</span></code> is.  Is it a single value to be altered in-place?
Is it an array, and if so what is its length?  Is it input-only?
Output-only?  Input-output?  <a class="reference external" href="http://www.swig.org">SWIG</a> cannot determine these details,
and does not attempt to do so.</p>
<p>If we designed <code class="docutils literal notranslate"><span class="pre">rms</span></code>, we probably made it a routine that takes an
input-only array of length <code class="docutils literal notranslate"><span class="pre">n</span></code> of <code class="docutils literal notranslate"><span class="pre">double</span></code> values called <code class="docutils literal notranslate"><span class="pre">seq</span></code>
and returns the root mean square.  The default behavior of <a class="reference external" href="http://www.swig.org">SWIG</a>,
however, will be to create a wrapper function that compiles, but is
nearly impossible to use from the scripting language in the way the C
routine was intended.</p>
<p>For Python, the preferred way of handling contiguous (or technically,
<em>strided</em>) blocks of homogeneous data is with NumPy, which provides full
object-oriented access to multidimensial arrays of data.  Therefore, the most
logical Python interface for the <code class="docutils literal notranslate"><span class="pre">rms</span></code> function would be (including doc
string):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">rms</span><span class="p">(</span><span class="n">seq</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    rms: return the root mean square of a sequence</span>
<span class="sd">    rms(numpy.ndarray) -&gt; double</span>
<span class="sd">    rms(list) -&gt; double</span>
<span class="sd">    rms(tuple) -&gt; double</span>
<span class="sd">    &quot;&quot;&quot;</span>
</pre></div>
</div>
<p>where <code class="docutils literal notranslate"><span class="pre">seq</span></code> would be a NumPy array of <code class="docutils literal notranslate"><span class="pre">double</span></code> values, and its
length <code class="docutils literal notranslate"><span class="pre">n</span></code> would be extracted from <code class="docutils literal notranslate"><span class="pre">seq</span></code> internally before being
passed to the C routine.  Even better, since NumPy supports
construction of arrays from arbitrary Python sequences, <code class="docutils literal notranslate"><span class="pre">seq</span></code>
itself could be a nearly arbitrary sequence (so long as each element
can be converted to a <code class="docutils literal notranslate"><span class="pre">double</span></code>) and the wrapper code would
internally convert it to a NumPy array before extracting its data
and length.</p>
<p><a class="reference external" href="http://www.swig.org">SWIG</a> allows these types of conversions to be defined via a
mechanism called <em>typemaps</em>.  This document provides information on
how to use <code class="docutils literal notranslate"><span class="pre">numpy.i</span></code>, a <a class="reference external" href="http://www.swig.org">SWIG</a> interface file that defines a series
of typemaps intended to make the type of array-related conversions
described above relatively simple to implement.  For example, suppose
that the <code class="docutils literal notranslate"><span class="pre">rms</span></code> function prototype defined above was in a header file
named <code class="docutils literal notranslate"><span class="pre">rms.h</span></code>.  To obtain the Python interface discussed above, your
<a class="reference external" href="http://www.swig.org">SWIG</a> interface file would need the following:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span><span class="p">{</span>
<span class="c1">#define SWIG_FILE_WITH_INIT</span>
<span class="c1">#include &quot;rms.h&quot;</span>
<span class="o">%</span><span class="p">}</span>

<span class="o">%</span><span class="n">include</span> <span class="s2">&quot;numpy.i&quot;</span>

<span class="o">%</span><span class="n">init</span> <span class="o">%</span><span class="p">{</span>
<span class="n">import_array</span><span class="p">();</span>
<span class="o">%</span><span class="p">}</span>

<span class="o">%</span><span class="n">apply</span> <span class="p">(</span><span class="n">double</span><span class="o">*</span> <span class="n">IN_ARRAY1</span><span class="p">,</span> <span class="nb">int</span> <span class="n">DIM1</span><span class="p">)</span> <span class="p">{(</span><span class="n">double</span><span class="o">*</span> <span class="n">seq</span><span class="p">,</span> <span class="nb">int</span> <span class="n">n</span><span class="p">)};</span>
<span class="o">%</span><span class="n">include</span> <span class="s2">&quot;rms.h&quot;</span>
</pre></div>
</div>
<p>Typemaps are keyed off a list of one or more function arguments,
either by type or by type and name.  We will refer to such lists as
<em>signatures</em>.  One of the many typemaps defined by <code class="docutils literal notranslate"><span class="pre">numpy.i</span></code> is used
above and has the signature <code class="docutils literal notranslate"><span class="pre">(double*</span> <span class="pre">IN_ARRAY1,</span> <span class="pre">int</span> <span class="pre">DIM1)</span></code>.  The
argument names are intended to suggest that the <code class="docutils literal notranslate"><span class="pre">double*</span></code> argument
is an input array of one dimension and that the <code class="docutils literal notranslate"><span class="pre">int</span></code> represents the
size of that dimension.  This is precisely the pattern in the <code class="docutils literal notranslate"><span class="pre">rms</span></code>
prototype.</p>
<p>Most likely, no actual prototypes to be wrapped will have the argument
names <code class="docutils literal notranslate"><span class="pre">IN_ARRAY1</span></code> and <code class="docutils literal notranslate"><span class="pre">DIM1</span></code>.  We use the <a class="reference external" href="http://www.swig.org">SWIG</a> <code class="docutils literal notranslate"><span class="pre">%apply</span></code>
directive to apply the typemap for one-dimensional input arrays of
type <code class="docutils literal notranslate"><span class="pre">double</span></code> to the actual prototype used by <code class="docutils literal notranslate"><span class="pre">rms</span></code>.  Using
<code class="docutils literal notranslate"><span class="pre">numpy.i</span></code> effectively, therefore, requires knowing what typemaps are
available and what they do.</p>
<p>A <a class="reference external" href="http://www.swig.org">SWIG</a> interface file that includes the <a class="reference external" href="http://www.swig.org">SWIG</a> directives given
above will produce wrapper code that looks something like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> 1 PyObject *_wrap_rms(PyObject *args) {
 2   PyObject *resultobj = 0;
 3   double *arg1 = (double *) 0 ;
 4   int arg2 ;
 5   double result;
 6   PyArrayObject *array1 = NULL ;
 7   int is_new_object1 = 0 ;
 8   PyObject * obj0 = 0 ;
 9
10   if (!PyArg_ParseTuple(args,(char *)&quot;O:rms&quot;,&amp;obj0)) SWIG_fail;
11   {
12     array1 = obj_to_array_contiguous_allow_conversion(
13                  obj0, NPY_DOUBLE, &amp;is_new_object1);
14     npy_intp size[1] = {
15       -1
16     };
17     if (!array1 || !require_dimensions(array1, 1) ||
18         !require_size(array1, size, 1)) SWIG_fail;
19     arg1 = (double*) array1-&gt;data;
20     arg2 = (int) array1-&gt;dimensions[0];
21   }
22   result = (double)rms(arg1,arg2);
23   resultobj = SWIG_From_double((double)(result));
24   {
25     if (is_new_object1 &amp;&amp; array1) Py_DECREF(array1);
26   }
27   return resultobj;
28 fail:
29   {
30     if (is_new_object1 &amp;&amp; array1) Py_DECREF(array1);
31   }
32   return NULL;
33 }
</pre></div>
</div>
<p>The typemaps from <code class="docutils literal notranslate"><span class="pre">numpy.i</span></code> are responsible for the following lines
of code: 12–20, 25 and 30.  Line 10 parses the input to the <code class="docutils literal notranslate"><span class="pre">rms</span></code>
function.  From the format string <code class="docutils literal notranslate"><span class="pre">&quot;O:rms&quot;</span></code>, we can see that the
argument list is expected to be a single Python object (specified
by the <code class="docutils literal notranslate"><span class="pre">O</span></code> before the colon) and whose pointer is stored in
<code class="docutils literal notranslate"><span class="pre">obj0</span></code>.  A number of functions, supplied by <code class="docutils literal notranslate"><span class="pre">numpy.i</span></code>, are called
to make and check the (possible) conversion from a generic Python
object to a NumPy array.  These functions are explained in the
section <a class="reference internal" href="#helper-functions">Helper Functions</a>, but hopefully their names are
self-explanatory.  At line 12 we use <code class="docutils literal notranslate"><span class="pre">obj0</span></code> to construct a NumPy
array.  At line 17, we check the validity of the result: that it is
non-null and that it has a single dimension of arbitrary length.  Once
these states are verified, we extract the data buffer and length in
lines 19 and 20 so that we can call the underlying C function at line
22.  Line 25 performs memory management for the case where we have
created a new array that is no longer needed.</p>
<p>This code has a significant amount of error handling.  Note the
<code class="docutils literal notranslate"><span class="pre">SWIG_fail</span></code> is a macro for <code class="docutils literal notranslate"><span class="pre">goto</span> <span class="pre">fail</span></code>, referring to the label at
line 28.  If the user provides the wrong number of arguments, this
will be caught at line 10.  If construction of the NumPy array
fails or produces an array with the wrong number of dimensions, these
errors are caught at line 17.  And finally, if an error is detected,
memory is still managed correctly at line 30.</p>
<p>Note that if the C function signature was in a different order:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">double</span> <span class="n">rms</span><span class="p">(</span><span class="nb">int</span> <span class="n">n</span><span class="p">,</span> <span class="n">double</span><span class="o">*</span> <span class="n">seq</span><span class="p">);</span>
</pre></div>
</div>
<p>that <a class="reference external" href="http://www.swig.org">SWIG</a> would not match the typemap signature given above with
the argument list for <code class="docutils literal notranslate"><span class="pre">rms</span></code>.  Fortunately, <code class="docutils literal notranslate"><span class="pre">numpy.i</span></code> has a set of
typemaps with the data pointer given last:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span><span class="n">apply</span> <span class="p">(</span><span class="nb">int</span> <span class="n">DIM1</span><span class="p">,</span> <span class="n">double</span><span class="o">*</span> <span class="n">IN_ARRAY1</span><span class="p">)</span> <span class="p">{(</span><span class="nb">int</span> <span class="n">n</span><span class="p">,</span> <span class="n">double</span><span class="o">*</span> <span class="n">seq</span><span class="p">)};</span>
</pre></div>
</div>
<p>This simply has the effect of switching the definitions of <code class="docutils literal notranslate"><span class="pre">arg1</span></code>
and <code class="docutils literal notranslate"><span class="pre">arg2</span></code> in lines 3 and 4 of the generated code above, and their
assignments in lines 19 and 20.</p>
</div>
<div class="section" id="using-numpy-i">
<h2>Using numpy.i<a class="headerlink" href="#using-numpy-i" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">numpy.i</span></code> file is currently located in the <code class="docutils literal notranslate"><span class="pre">tools/swig</span></code>
sub-directory under the <code class="docutils literal notranslate"><span class="pre">numpy</span></code> installation directory.  Typically,
you will want to copy it to the directory where you are developing
your wrappers.</p>
<p>A simple module that only uses a single <a class="reference external" href="http://www.swig.org">SWIG</a> interface file should
include the following:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span><span class="p">{</span>
<span class="c1">#define SWIG_FILE_WITH_INIT</span>
<span class="o">%</span><span class="p">}</span>
<span class="o">%</span><span class="n">include</span> <span class="s2">&quot;numpy.i&quot;</span>
<span class="o">%</span><span class="n">init</span> <span class="o">%</span><span class="p">{</span>
<span class="n">import_array</span><span class="p">();</span>
<span class="o">%</span><span class="p">}</span>
</pre></div>
</div>
<p>Within a compiled Python module, <code class="docutils literal notranslate"><span class="pre">import_array()</span></code> should only get
called once.  This could be in a C/C++ file that you have written and
is linked to the module.  If this is the case, then none of your
interface files should <code class="docutils literal notranslate"><span class="pre">#define</span> <span class="pre">SWIG_FILE_WITH_INIT</span></code> or call
<code class="docutils literal notranslate"><span class="pre">import_array()</span></code>.  Or, this initialization call could be in a
wrapper file generated by <a class="reference external" href="http://www.swig.org">SWIG</a> from an interface file that has the
<code class="docutils literal notranslate"><span class="pre">%init</span></code> block as above.  If this is the case, and you have more than
one <a class="reference external" href="http://www.swig.org">SWIG</a> interface file, then only one interface file should
<code class="docutils literal notranslate"><span class="pre">#define</span> <span class="pre">SWIG_FILE_WITH_INIT</span></code> and call <code class="docutils literal notranslate"><span class="pre">import_array()</span></code>.</p>
</div>
<div class="section" id="available-typemaps">
<h2>Available Typemaps<a class="headerlink" href="#available-typemaps" title="Permalink to this headline">¶</a></h2>
<p>The typemap directives provided by <code class="docutils literal notranslate"><span class="pre">numpy.i</span></code> for arrays of different
data types, say <code class="docutils literal notranslate"><span class="pre">double</span></code> and <code class="docutils literal notranslate"><span class="pre">int</span></code>, and dimensions of different
types, say <code class="docutils literal notranslate"><span class="pre">int</span></code> or <code class="docutils literal notranslate"><span class="pre">long</span></code>, are identical to one another except
for the C and NumPy type specifications.  The typemaps are
therefore implemented (typically behind the scenes) via a macro:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span><span class="n">numpy_typemaps</span><span class="p">(</span><span class="n">DATA_TYPE</span><span class="p">,</span> <span class="n">DATA_TYPECODE</span><span class="p">,</span> <span class="n">DIM_TYPE</span><span class="p">)</span>
</pre></div>
</div>
<p>that can be invoked for appropriate <code class="docutils literal notranslate"><span class="pre">(DATA_TYPE,</span> <span class="pre">DATA_TYPECODE,</span>
<span class="pre">DIM_TYPE)</span></code> triplets.  For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span><span class="n">numpy_typemaps</span><span class="p">(</span><span class="n">double</span><span class="p">,</span> <span class="n">NPY_DOUBLE</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
<span class="o">%</span><span class="n">numpy_typemaps</span><span class="p">(</span><span class="nb">int</span><span class="p">,</span>    <span class="n">NPY_INT</span>   <span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">numpy.i</span></code> interface file uses the <code class="docutils literal notranslate"><span class="pre">%numpy_typemaps</span></code> macro to
implement typemaps for the following C data types and <code class="docutils literal notranslate"><span class="pre">int</span></code>
dimension types:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">signed</span> <span class="pre">char</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">char</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">short</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">short</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">int</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">int</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">long</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">long</span> <span class="pre">long</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">float</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">double</span></code></p></li>
</ul>
</div></blockquote>
<p>In the following descriptions, we reference a generic <code class="docutils literal notranslate"><span class="pre">DATA_TYPE</span></code>, which
could be any of the C data types listed above, and <code class="docutils literal notranslate"><span class="pre">DIM_TYPE</span></code> which
should be one of the many types of integers.</p>
<p>The typemap signatures are largely differentiated on the name given to
the buffer pointer.  Names with <code class="docutils literal notranslate"><span class="pre">FARRAY</span></code> are for Fortran-ordered
arrays, and names with <code class="docutils literal notranslate"><span class="pre">ARRAY</span></code> are for C-ordered (or 1D arrays).</p>
<div class="section" id="input-arrays">
<h3>Input Arrays<a class="headerlink" href="#input-arrays" title="Permalink to this headline">¶</a></h3>
<p>Input arrays are defined as arrays of data that are passed into a
routine but are not altered in-place or returned to the user.  The
Python input array is therefore allowed to be almost any Python
sequence (such as a list) that can be converted to the requested type
of array.  The input array signatures are</p>
<p>1D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">IN_ARRAY1[ANY]</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_ARRAY1,</span> <span class="pre">int</span> <span class="pre">DIM1</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_ARRAY1</span> <span class="pre">)</span></code></p></li>
</ul>
</div></blockquote>
<p>2D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">IN_ARRAY2[ANY][ANY]</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_ARRAY2,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_ARRAY2</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_FARRAY2,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_FARRAY2</span> <span class="pre">)</span></code></p></li>
</ul>
</div></blockquote>
<p>3D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">IN_ARRAY3[ANY][ANY][ANY]</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_ARRAY3,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_ARRAY3</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_FARRAY3,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_FARRAY3</span> <span class="pre">)</span></code></p></li>
</ul>
</div></blockquote>
<p>4D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(DATA_TYPE</span> <span class="pre">IN_ARRAY4[ANY][ANY][ANY][ANY])</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DATA_TYPE*</span> <span class="pre">IN_ARRAY4,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM3,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM4)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DIM_TYPE</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM3,</span> <span class="pre">,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM4,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_ARRAY4)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DATA_TYPE*</span> <span class="pre">IN_FARRAY4,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM3,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM4)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DIM_TYPE</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM3,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM4,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_FARRAY4)</span></code></p></li>
</ul>
</div></blockquote>
<p>The first signature listed, <code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">IN_ARRAY[ANY]</span> <span class="pre">)</span></code> is for
one-dimensional arrays with hard-coded dimensions.  Likewise,
<code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">IN_ARRAY2[ANY][ANY]</span> <span class="pre">)</span></code> is for two-dimensional arrays
with hard-coded dimensions, and similarly for three-dimensional.</p>
</div>
<div class="section" id="in-place-arrays">
<h3>In-Place Arrays<a class="headerlink" href="#in-place-arrays" title="Permalink to this headline">¶</a></h3>
<p>In-place arrays are defined as arrays that are modified in-place.  The
input values may or may not be used, but the values at the time the
function returns are significant.  The provided Python argument
must therefore be a NumPy array of the required type.  The in-place
signatures are</p>
<p>1D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">INPLACE_ARRAY1[ANY]</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY1,</span> <span class="pre">int</span> <span class="pre">DIM1</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY1</span> <span class="pre">)</span></code></p></li>
</ul>
</div></blockquote>
<p>2D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">INPLACE_ARRAY2[ANY][ANY]</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY2,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY2</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_FARRAY2,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_FARRAY2</span> <span class="pre">)</span></code></p></li>
</ul>
</div></blockquote>
<p>3D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">INPLACE_ARRAY3[ANY][ANY][ANY]</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY3,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY3</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_FARRAY3,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_FARRAY3</span> <span class="pre">)</span></code></p></li>
</ul>
</div></blockquote>
<p>4D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(DATA_TYPE</span> <span class="pre">INPLACE_ARRAY4[ANY][ANY][ANY][ANY])</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY4,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM3,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM4)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DIM_TYPE</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM3,</span> <span class="pre">,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM4,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY4)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DATA_TYPE*</span> <span class="pre">INPLACE_FARRAY4,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM3,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM4)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DIM_TYPE</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM3,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM4,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_FARRAY4)</span></code></p></li>
</ul>
</div></blockquote>
<p>These typemaps now check to make sure that the <code class="docutils literal notranslate"><span class="pre">INPLACE_ARRAY</span></code>
arguments use native byte ordering.  If not, an exception is raised.</p>
<p>There is also a “flat” in-place array for situations in which
you would like to modify or process each element, regardless of the
number of dimensions. One example is a “quantization” function that
quantizes each element of an array in-place, be it 1D, 2D or whatever.
This form checks for continuity but allows either C or Fortran ordering.</p>
<p>ND:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY_FLAT,</span> <span class="pre">DIM_TYPE</span> <span class="pre">DIM_FLAT)</span></code></p></li>
</ul>
</div></blockquote>
</div>
<div class="section" id="argout-arrays">
<h3>Argout Arrays<a class="headerlink" href="#argout-arrays" title="Permalink to this headline">¶</a></h3>
<p>Argout arrays are arrays that appear in the input arguments in C, but
are in fact output arrays.  This pattern occurs often when there is
more than one output variable and the single return argument is
therefore not sufficient.  In Python, the conventional way to return
multiple arguments is to pack them into a sequence (tuple, list, etc.)
and return the sequence.  This is what the argout typemaps do.  If a
wrapped function that uses these argout typemaps has more than one
return argument, they are packed into a tuple or list, depending on
the version of Python.  The Python user does not pass these
arrays in, they simply get returned.  For the case where a dimension
is specified, the python user must provide that dimension as an
argument.  The argout signatures are</p>
<p>1D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">ARGOUT_ARRAY1[ANY]</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE*</span> <span class="pre">ARGOUT_ARRAY1,</span> <span class="pre">int</span> <span class="pre">DIM1</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">ARGOUT_ARRAY1</span> <span class="pre">)</span></code></p></li>
</ul>
</div></blockquote>
<p>2D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">ARGOUT_ARRAY2[ANY][ANY]</span> <span class="pre">)</span></code></p></li>
</ul>
</div></blockquote>
<p>3D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">ARGOUT_ARRAY3[ANY][ANY][ANY]</span> <span class="pre">)</span></code></p></li>
</ul>
</div></blockquote>
<p>4D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE</span> <span class="pre">ARGOUT_ARRAY4[ANY][ANY][ANY][ANY]</span> <span class="pre">)</span></code></p></li>
</ul>
</div></blockquote>
<p>These are typically used in situations where in C/C++, you would
allocate a(n) array(s) on the heap, and call the function to fill the
array(s) values.  In Python, the arrays are allocated for you and
returned as new array objects.</p>
<p>Note that we support <code class="docutils literal notranslate"><span class="pre">DATA_TYPE*</span></code> argout typemaps in 1D, but not 2D
or 3D.  This is because of a quirk with the <a class="reference external" href="http://www.swig.org">SWIG</a> typemap syntax and
cannot be avoided.  Note that for these types of 1D typemaps, the
Python function will take a single argument representing <code class="docutils literal notranslate"><span class="pre">DIM1</span></code>.</p>
</div>
<div class="section" id="argout-view-arrays">
<h3>Argout View Arrays<a class="headerlink" href="#argout-view-arrays" title="Permalink to this headline">¶</a></h3>
<p>Argoutview arrays are for when your C code provides you with a view of
its internal data and does not require any memory to be allocated by
the user.  This can be dangerous.  There is almost no way to guarantee
that the internal data from the C code will remain in existence for
the entire lifetime of the NumPy array that encapsulates it.  If
the user destroys the object that provides the view of the data before
destroying the NumPy array, then using that array may result in bad
memory references or segmentation faults.  Nevertheless, there are
situations, working with large data sets, where you simply have no
other choice.</p>
<p>The C code to be wrapped for argoutview arrays are characterized by
pointers: pointers to the dimensions and double pointers to the data,
so that these values can be passed back to the user.  The argoutview
typemap signatures are therefore</p>
<p>1D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_ARRAY1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_ARRAY1</span> <span class="pre">)</span></code></p></li>
</ul>
</div></blockquote>
<p>2D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_ARRAY2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_ARRAY2</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_FARRAY2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2</span> <span class="pre">)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_FARRAY2</span> <span class="pre">)</span></code></p></li>
</ul>
</div></blockquote>
<p>3D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_ARRAY3,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_ARRAY3)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_FARRAY3,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_FARRAY3)</span></code></p></li>
</ul>
</div></blockquote>
<p>4D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_ARRAY4,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM4)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM4,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_ARRAY4)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_FARRAY4,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM4)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM4,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEW_FARRAY4)</span></code></p></li>
</ul>
</div></blockquote>
<p>Note that arrays with hard-coded dimensions are not supported.  These
cannot follow the double pointer signatures of these typemaps.</p>
</div>
<div class="section" id="memory-managed-argout-view-arrays">
<h3>Memory Managed Argout View Arrays<a class="headerlink" href="#memory-managed-argout-view-arrays" title="Permalink to this headline">¶</a></h3>
<p>A recent addition to <code class="docutils literal notranslate"><span class="pre">numpy.i</span></code> are typemaps that permit argout
arrays with views into memory that is managed.  See the discussion <a class="reference external" href="http://blog.enthought.com/python/numpy-arrays-with-pre-allocated-memory">here</a>.</p>
<p>1D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(DATA_TYPE**</span> <span class="pre">ARGOUTVIEWM_ARRAY1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEWM_ARRAY1)</span></code></p></li>
</ul>
</div></blockquote>
<p>2D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(DATA_TYPE**</span> <span class="pre">ARGOUTVIEWM_ARRAY2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEWM_ARRAY2)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DATA_TYPE**</span> <span class="pre">ARGOUTVIEWM_FARRAY2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEWM_FARRAY2)</span></code></p></li>
</ul>
</div></blockquote>
<p>3D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(DATA_TYPE**</span> <span class="pre">ARGOUTVIEWM_ARRAY3,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEWM_ARRAY3)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DATA_TYPE**</span> <span class="pre">ARGOUTVIEWM_FARRAY3,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEWM_FARRAY3)</span></code></p></li>
</ul>
</div></blockquote>
<p>4D:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">(DATA_TYPE**</span> <span class="pre">ARGOUTVIEWM_ARRAY4,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM4)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM4,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEWM_ARRAY4)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DATA_TYPE**</span> <span class="pre">ARGOUTVIEWM_FARRAY4,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM4)</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">(DIM_TYPE*</span> <span class="pre">DIM1,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM2,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM3,</span> <span class="pre">DIM_TYPE*</span> <span class="pre">DIM4,</span> <span class="pre">DATA_TYPE**</span> <span class="pre">ARGOUTVIEWM_FARRAY4)</span></code></p></li>
</ul>
</div></blockquote>
</div>
<div class="section" id="output-arrays">
<h3>Output Arrays<a class="headerlink" href="#output-arrays" title="Permalink to this headline">¶</a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">numpy.i</span></code> interface file does not support typemaps for output
arrays, for several reasons.  First, C/C++ return arguments are
limited to a single value.  This prevents obtaining dimension
information in a general way.  Second, arrays with hard-coded lengths
are not permitted as return arguments.  In other words:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">double</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span> <span class="n">newVector</span><span class="p">(</span><span class="n">double</span> <span class="n">x</span><span class="p">,</span> <span class="n">double</span> <span class="n">y</span><span class="p">,</span> <span class="n">double</span> <span class="n">z</span><span class="p">);</span>
</pre></div>
</div>
<p>is not legal C/C++ syntax.  Therefore, we cannot provide typemaps of
the form:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span><span class="n">typemap</span><span class="p">(</span><span class="n">out</span><span class="p">)</span> <span class="p">(</span><span class="n">TYPE</span><span class="p">[</span><span class="n">ANY</span><span class="p">]);</span>
</pre></div>
</div>
<p>If you run into a situation where a function or method is returning a
pointer to an array, your best bet is to write your own version of the
function to be wrapped, either with <code class="docutils literal notranslate"><span class="pre">%extend</span></code> for the case of class
methods or <code class="docutils literal notranslate"><span class="pre">%ignore</span></code> and <code class="docutils literal notranslate"><span class="pre">%rename</span></code> for the case of functions.</p>
</div>
<div class="section" id="other-common-types-bool">
<h3>Other Common Types: bool<a class="headerlink" href="#other-common-types-bool" title="Permalink to this headline">¶</a></h3>
<p>Note that C++ type <code class="docutils literal notranslate"><span class="pre">bool</span></code> is not supported in the list in the
<a class="reference internal" href="#available-typemaps">Available Typemaps</a> section.  NumPy bools are a single byte, while
the C++ <code class="docutils literal notranslate"><span class="pre">bool</span></code> is four bytes (at least on my system).  Therefore:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span><span class="n">numpy_typemaps</span><span class="p">(</span><span class="nb">bool</span><span class="p">,</span> <span class="n">NPY_BOOL</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
</pre></div>
</div>
<p>will result in typemaps that will produce code that reference
improper data lengths.  You can implement the following macro
expansion:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span><span class="n">numpy_typemaps</span><span class="p">(</span><span class="nb">bool</span><span class="p">,</span> <span class="n">NPY_UINT</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
</pre></div>
</div>
<p>to fix the data length problem, and <a class="reference internal" href="#input-arrays">Input Arrays</a> will work fine,
but <a class="reference internal" href="#in-place-arrays">In-Place Arrays</a> might fail type-checking.</p>
</div>
<div class="section" id="other-common-types-complex">
<h3>Other Common Types: complex<a class="headerlink" href="#other-common-types-complex" title="Permalink to this headline">¶</a></h3>
<p>Typemap conversions for complex floating-point types is also not
supported automatically.  This is because Python and NumPy are
written in C, which does not have native complex types.  Both
Python and NumPy implement their own (essentially equivalent)
<code class="docutils literal notranslate"><span class="pre">struct</span></code> definitions for complex variables:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">/*</span> <span class="n">Python</span> <span class="o">*/</span>
<span class="n">typedef</span> <span class="n">struct</span> <span class="p">{</span><span class="n">double</span> <span class="n">real</span><span class="p">;</span> <span class="n">double</span> <span class="n">imag</span><span class="p">;}</span> <span class="n">Py_complex</span><span class="p">;</span>

<span class="o">/*</span> <span class="n">NumPy</span> <span class="o">*/</span>
<span class="n">typedef</span> <span class="n">struct</span> <span class="p">{</span><span class="nb">float</span>  <span class="n">real</span><span class="p">,</span> <span class="n">imag</span><span class="p">;}</span> <span class="n">npy_cfloat</span><span class="p">;</span>
<span class="n">typedef</span> <span class="n">struct</span> <span class="p">{</span><span class="n">double</span> <span class="n">real</span><span class="p">,</span> <span class="n">imag</span><span class="p">;}</span> <span class="n">npy_cdouble</span><span class="p">;</span>
</pre></div>
</div>
<p>We could have implemented:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span><span class="n">numpy_typemaps</span><span class="p">(</span><span class="n">Py_complex</span> <span class="p">,</span> <span class="n">NPY_CDOUBLE</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
<span class="o">%</span><span class="n">numpy_typemaps</span><span class="p">(</span><span class="n">npy_cfloat</span> <span class="p">,</span> <span class="n">NPY_CFLOAT</span> <span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
<span class="o">%</span><span class="n">numpy_typemaps</span><span class="p">(</span><span class="n">npy_cdouble</span><span class="p">,</span> <span class="n">NPY_CDOUBLE</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>
</pre></div>
</div>
<p>which would have provided automatic type conversions for arrays of
type <code class="docutils literal notranslate"><span class="pre">Py_complex</span></code>, <code class="docutils literal notranslate"><span class="pre">npy_cfloat</span></code> and <code class="docutils literal notranslate"><span class="pre">npy_cdouble</span></code>.  However, it
seemed unlikely that there would be any independent (non-Python,
non-NumPy) application code that people would be using <a class="reference external" href="http://www.swig.org">SWIG</a> to
generate a Python interface to, that also used these definitions
for complex types.  More likely, these application codes will define
their own complex types, or in the case of C++, use <code class="docutils literal notranslate"><span class="pre">std::complex</span></code>.
Assuming these data structures are compatible with Python and
NumPy complex types, <code class="docutils literal notranslate"><span class="pre">%numpy_typemap</span></code> expansions as above (with
the user’s complex type substituted for the first argument) should
work.</p>
</div>
</div>
<div class="section" id="numpy-array-scalars-and-swig">
<h2>NumPy Array Scalars and SWIG<a class="headerlink" href="#numpy-array-scalars-and-swig" title="Permalink to this headline">¶</a></h2>
<p><a class="reference external" href="http://www.swig.org">SWIG</a> has sophisticated type checking for numerical types.  For
example, if your C/C++ routine expects an integer as input, the code
generated by <a class="reference external" href="http://www.swig.org">SWIG</a> will check for both Python integers and
Python long integers, and raise an overflow error if the provided
Python integer is too big to cast down to a C integer.  With the
introduction of NumPy scalar arrays into your Python code, you
might conceivably extract an integer from a NumPy array and attempt
to pass this to a <a class="reference external" href="http://www.swig.org">SWIG</a>-wrapped C/C++ function that expects an
<code class="docutils literal notranslate"><span class="pre">int</span></code>, but the <a class="reference external" href="http://www.swig.org">SWIG</a> type checking will not recognize the NumPy
array scalar as an integer.  (Often, this does in fact work – it
depends on whether NumPy recognizes the integer type you are using
as inheriting from the Python integer type on the platform you are
using.  Sometimes, this means that code that works on a 32-bit machine
will fail on a 64-bit machine.)</p>
<p>If you get a Python error that looks like the following:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="ne">TypeError</span><span class="p">:</span> <span class="ow">in</span> <span class="n">method</span> <span class="s1">&#39;MyClass_MyMethod&#39;</span><span class="p">,</span> <span class="n">argument</span> <span class="mi">2</span> <span class="n">of</span> <span class="nb">type</span> <span class="s1">&#39;int&#39;</span>
</pre></div>
</div>
<p>and the argument you are passing is an integer extracted from a
NumPy array, then you have stumbled upon this problem.  The
solution is to modify the <a class="reference external" href="http://www.swig.org">SWIG</a> type conversion system to accept
NumPy array scalars in addition to the standard integer types.
Fortunately, this capability has been provided for you.  Simply copy
the file:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pyfragments</span><span class="o">.</span><span class="n">swg</span>
</pre></div>
</div>
<p>to the working build directory for you project, and this problem will
be fixed.  It is suggested that you do this anyway, as it only
increases the capabilities of your Python interface.</p>
<div class="section" id="why-is-there-a-second-file">
<h3>Why is There a Second File?<a class="headerlink" href="#why-is-there-a-second-file" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference external" href="http://www.swig.org">SWIG</a> type checking and conversion system is a complicated
combination of C macros, <a class="reference external" href="http://www.swig.org">SWIG</a> macros, <a class="reference external" href="http://www.swig.org">SWIG</a> typemaps and <a class="reference external" href="http://www.swig.org">SWIG</a>
fragments.  Fragments are a way to conditionally insert code into your
wrapper file if it is needed, and not insert it if not needed.  If
multiple typemaps require the same fragment, the fragment only gets
inserted into your wrapper code once.</p>
<p>There is a fragment for converting a Python integer to a C
<code class="docutils literal notranslate"><span class="pre">long</span></code>.  There is a different fragment that converts a Python
integer to a C <code class="docutils literal notranslate"><span class="pre">int</span></code>, that calls the routine defined in the
<code class="docutils literal notranslate"><span class="pre">long</span></code> fragment.  We can make the changes we want here by changing
the definition for the <code class="docutils literal notranslate"><span class="pre">long</span></code> fragment.  <a class="reference external" href="http://www.swig.org">SWIG</a> determines the
active definition for a fragment using a “first come, first served”
system.  That is, we need to define the fragment for <code class="docutils literal notranslate"><span class="pre">long</span></code>
conversions prior to <a class="reference external" href="http://www.swig.org">SWIG</a> doing it internally.  <a class="reference external" href="http://www.swig.org">SWIG</a> allows us
to do this by putting our fragment definitions in the file
<code class="docutils literal notranslate"><span class="pre">pyfragments.swg</span></code>.  If we were to put the new fragment definitions
in <code class="docutils literal notranslate"><span class="pre">numpy.i</span></code>, they would be ignored.</p>
</div>
</div>
<div class="section" id="helper-functions">
<h2>Helper Functions<a class="headerlink" href="#helper-functions" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">numpy.i</span></code> file contains several macros and routines that it
uses internally to build its typemaps.  However, these functions may
be useful elsewhere in your interface file.  These macros and routines
are implemented as fragments, which are described briefly in the
previous section.  If you try to use one or more of the following
macros or functions, but your compiler complains that it does not
recognize the symbol, then you need to force these fragments to appear
in your code using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span><span class="n">fragment</span><span class="p">(</span><span class="s2">&quot;NumPy_Fragments&quot;</span><span class="p">);</span>
</pre></div>
</div>
<p>in your <a class="reference external" href="http://www.swig.org">SWIG</a> interface file.</p>
<div class="section" id="macros">
<h3>Macros<a class="headerlink" href="#macros" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><dl class="simple">
<dt><strong>is_array(a)</strong></dt><dd><p>Evaluates as true if <code class="docutils literal notranslate"><span class="pre">a</span></code> is non-<code class="docutils literal notranslate"><span class="pre">NULL</span></code> and can be cast to a
<code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code>.</p>
</dd>
<dt><strong>array_type(a)</strong></dt><dd><p>Evaluates to the integer data type code of <code class="docutils literal notranslate"><span class="pre">a</span></code>, assuming <code class="docutils literal notranslate"><span class="pre">a</span></code> can
be cast to a <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code>.</p>
</dd>
<dt><strong>array_numdims(a)</strong></dt><dd><p>Evaluates to the integer number of dimensions of <code class="docutils literal notranslate"><span class="pre">a</span></code>, assuming
<code class="docutils literal notranslate"><span class="pre">a</span></code> can be cast to a <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code>.</p>
</dd>
<dt><strong>array_dimensions(a)</strong></dt><dd><p>Evaluates to an array of type <code class="docutils literal notranslate"><span class="pre">npy_intp</span></code> and length
<code class="docutils literal notranslate"><span class="pre">array_numdims(a)</span></code>, giving the lengths of all of the dimensions
of <code class="docutils literal notranslate"><span class="pre">a</span></code>, assuming <code class="docutils literal notranslate"><span class="pre">a</span></code> can be cast to a <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code>.</p>
</dd>
<dt><strong>array_size(a,i)</strong></dt><dd><p>Evaluates to the <code class="docutils literal notranslate"><span class="pre">i</span></code>-th dimension size of <code class="docutils literal notranslate"><span class="pre">a</span></code>, assuming <code class="docutils literal notranslate"><span class="pre">a</span></code>
can be cast to a <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code>.</p>
</dd>
<dt><strong>array_strides(a)</strong></dt><dd><p>Evaluates to an array of type <code class="docutils literal notranslate"><span class="pre">npy_intp</span></code> and length
<code class="docutils literal notranslate"><span class="pre">array_numdims(a)</span></code>, giving the stridess of all of the dimensions
of <code class="docutils literal notranslate"><span class="pre">a</span></code>, assuming <code class="docutils literal notranslate"><span class="pre">a</span></code> can be cast to a <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code>.  A
stride is the distance in bytes between an element and its
immediate neighbor along the same axis.</p>
</dd>
<dt><strong>array_stride(a,i)</strong></dt><dd><p>Evaluates to the <code class="docutils literal notranslate"><span class="pre">i</span></code>-th stride of <code class="docutils literal notranslate"><span class="pre">a</span></code>, assuming <code class="docutils literal notranslate"><span class="pre">a</span></code> can be
cast to a <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code>.</p>
</dd>
<dt><strong>array_data(a)</strong></dt><dd><p>Evaluates to a pointer of type <code class="docutils literal notranslate"><span class="pre">void*</span></code> that points to the data
buffer of <code class="docutils literal notranslate"><span class="pre">a</span></code>, assuming <code class="docutils literal notranslate"><span class="pre">a</span></code> can be cast to a <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code>.</p>
</dd>
<dt><strong>array_descr(a)</strong></dt><dd><p>Returns a borrowed reference to the dtype property
(<code class="docutils literal notranslate"><span class="pre">PyArray_Descr*</span></code>) of <code class="docutils literal notranslate"><span class="pre">a</span></code>, assuming <code class="docutils literal notranslate"><span class="pre">a</span></code> can be cast to a
<code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code>.</p>
</dd>
<dt><strong>array_flags(a)</strong></dt><dd><p>Returns an integer representing the flags of <code class="docutils literal notranslate"><span class="pre">a</span></code>, assuming <code class="docutils literal notranslate"><span class="pre">a</span></code>
can be cast to a <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code>.</p>
</dd>
<dt><strong>array_enableflags(a,f)</strong></dt><dd><p>Sets the flag represented by <code class="docutils literal notranslate"><span class="pre">f</span></code> of <code class="docutils literal notranslate"><span class="pre">a</span></code>, assuming <code class="docutils literal notranslate"><span class="pre">a</span></code> can be
cast to a <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code>.</p>
</dd>
<dt><strong>array_is_contiguous(a)</strong></dt><dd><p>Evaluates as true if <code class="docutils literal notranslate"><span class="pre">a</span></code> is a contiguous array.  Equivalent to
<code class="docutils literal notranslate"><span class="pre">(PyArray_ISCONTIGUOUS(a))</span></code>.</p>
</dd>
<dt><strong>array_is_native(a)</strong></dt><dd><p>Evaluates as true if the data buffer of <code class="docutils literal notranslate"><span class="pre">a</span></code> uses native byte
order.  Equivalent to <code class="docutils literal notranslate"><span class="pre">(PyArray_ISNOTSWAPPED(a))</span></code>.</p>
</dd>
<dt><strong>array_is_fortran(a)</strong></dt><dd><p>Evaluates as true if <code class="docutils literal notranslate"><span class="pre">a</span></code> is FORTRAN ordered.</p>
</dd>
</dl>
</div></blockquote>
</div>
<div class="section" id="routines">
<h3>Routines<a class="headerlink" href="#routines" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><p><strong>pytype_string()</strong></p>
<blockquote>
<div><p>Return type: <code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">char*</span></code></p>
<p>Arguments:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">PyObject*</span> <span class="pre">py_obj</span></code>, a general Python object.</p></li>
</ul>
<p>Return a string describing the type of <code class="docutils literal notranslate"><span class="pre">py_obj</span></code>.</p>
</div></blockquote>
<p><strong>typecode_string()</strong></p>
<blockquote>
<div><p>Return type: <code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">char*</span></code></p>
<p>Arguments:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">typecode</span></code>, a NumPy integer typecode.</p></li>
</ul>
<p>Return a string describing the type corresponding to the NumPy
<code class="docutils literal notranslate"><span class="pre">typecode</span></code>.</p>
</div></blockquote>
<p><strong>type_match()</strong></p>
<blockquote>
<div><p>Return type: <code class="docutils literal notranslate"><span class="pre">int</span></code></p>
<p>Arguments:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">actual_type</span></code>, the NumPy typecode of a NumPy array.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">desired_type</span></code>, the desired NumPy typecode.</p></li>
</ul>
<p>Make sure that <code class="docutils literal notranslate"><span class="pre">actual_type</span></code> is compatible with
<code class="docutils literal notranslate"><span class="pre">desired_type</span></code>.  For example, this allows character and
byte types, or int and long types, to match.  This is now
equivalent to <code class="docutils literal notranslate"><span class="pre">PyArray_EquivTypenums()</span></code>.</p>
</div></blockquote>
<p><strong>obj_to_array_no_conversion()</strong></p>
<blockquote>
<div><p>Return type: <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code></p>
<p>Arguments:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">PyObject*</span> <span class="pre">input</span></code>, a general Python object.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">typecode</span></code>, the desired NumPy typecode.</p></li>
</ul>
<p>Cast <code class="docutils literal notranslate"><span class="pre">input</span></code> to a <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code> if legal, and ensure that
it is of type <code class="docutils literal notranslate"><span class="pre">typecode</span></code>.  If <code class="docutils literal notranslate"><span class="pre">input</span></code> cannot be cast, or the
<code class="docutils literal notranslate"><span class="pre">typecode</span></code> is wrong, set a Python error and return <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>
</div></blockquote>
<p><strong>obj_to_array_allow_conversion()</strong></p>
<blockquote>
<div><p>Return type: <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code></p>
<p>Arguments:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">PyObject*</span> <span class="pre">input</span></code>, a general Python object.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">typecode</span></code>, the desired NumPy typecode of the resulting
array.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">int*</span> <span class="pre">is_new_object</span></code>, returns a value of 0 if no conversion
performed, else 1.</p></li>
</ul>
<p>Convert <code class="docutils literal notranslate"><span class="pre">input</span></code> to a NumPy array with the given <code class="docutils literal notranslate"><span class="pre">typecode</span></code>.
On success, return a valid <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code> with the correct
type.  On failure, the Python error string will be set and the
routine returns <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>
</div></blockquote>
<p><strong>make_contiguous()</strong></p>
<blockquote>
<div><p>Return type: <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code></p>
<p>Arguments:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span> <span class="pre">ary</span></code>, a NumPy array.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">int*</span> <span class="pre">is_new_object</span></code>, returns a value of 0 if no conversion
performed, else 1.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">min_dims</span></code>, minimum allowable dimensions.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">max_dims</span></code>, maximum allowable dimensions.</p></li>
</ul>
<p>Check to see if <code class="docutils literal notranslate"><span class="pre">ary</span></code> is contiguous.  If so, return the input
pointer and flag it as not a new object.  If it is not contiguous,
create a new <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code> using the original data, flag it
as a new object and return the pointer.</p>
</div></blockquote>
<p><strong>make_fortran()</strong></p>
<blockquote>
<div><p>Return type: <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code></p>
<p>Arguments</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span> <span class="pre">ary</span></code>, a NumPy array.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">int*</span> <span class="pre">is_new_object</span></code>, returns a value of 0 if no conversion
performed, else 1.</p></li>
</ul>
<p>Check to see if <code class="docutils literal notranslate"><span class="pre">ary</span></code> is Fortran contiguous.  If so, return the
input pointer and flag it as not a new object.  If it is not
Fortran contiguous, create a new <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code> using the
original data, flag it as a new object and return the pointer.</p>
</div></blockquote>
<p><strong>obj_to_array_contiguous_allow_conversion()</strong></p>
<blockquote>
<div><p>Return type: <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code></p>
<p>Arguments:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">PyObject*</span> <span class="pre">input</span></code>, a general Python object.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">typecode</span></code>, the desired NumPy typecode of the resulting
array.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">int*</span> <span class="pre">is_new_object</span></code>, returns a value of 0 if no conversion
performed, else 1.</p></li>
</ul>
<p>Convert <code class="docutils literal notranslate"><span class="pre">input</span></code> to a contiguous <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code> of the
specified type.  If the input object is not a contiguous
<code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code>, a new one will be created and the new object
flag will be set.</p>
</div></blockquote>
<p><strong>obj_to_array_fortran_allow_conversion()</strong></p>
<blockquote>
<div><p>Return type: <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code></p>
<p>Arguments:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">PyObject*</span> <span class="pre">input</span></code>, a general Python object.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">typecode</span></code>, the desired NumPy typecode of the resulting
array.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">int*</span> <span class="pre">is_new_object</span></code>, returns a value of 0 if no conversion
performed, else 1.</p></li>
</ul>
<p>Convert <code class="docutils literal notranslate"><span class="pre">input</span></code> to a Fortran contiguous <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code> of
the specified type.  If the input object is not a Fortran
contiguous <code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code>, a new one will be created and the
new object flag will be set.</p>
</div></blockquote>
<p><strong>require_contiguous()</strong></p>
<blockquote>
<div><p>Return type: <code class="docutils literal notranslate"><span class="pre">int</span></code></p>
<p>Arguments:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span> <span class="pre">ary</span></code>, a NumPy array.</p></li>
</ul>
<p>Test whether <code class="docutils literal notranslate"><span class="pre">ary</span></code> is contiguous.  If so, return 1.  Otherwise,
set a Python error and return 0.</p>
</div></blockquote>
<p><strong>require_native()</strong></p>
<blockquote>
<div><p>Return type: <code class="docutils literal notranslate"><span class="pre">int</span></code></p>
<p>Arguments:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">PyArray_Object*</span> <span class="pre">ary</span></code>, a NumPy array.</p></li>
</ul>
<p>Require that <code class="docutils literal notranslate"><span class="pre">ary</span></code> is not byte-swapped.  If the array is not
byte-swapped, return 1.  Otherwise, set a Python error and
return 0.</p>
</div></blockquote>
<p><strong>require_dimensions()</strong></p>
<blockquote>
<div><p>Return type: <code class="docutils literal notranslate"><span class="pre">int</span></code></p>
<p>Arguments:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span> <span class="pre">ary</span></code>, a NumPy array.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">exact_dimensions</span></code>, the desired number of dimensions.</p></li>
</ul>
<p>Require <code class="docutils literal notranslate"><span class="pre">ary</span></code> to have a specified number of dimensions.  If the
array has the specified number of dimensions, return 1.
Otherwise, set a Python error and return 0.</p>
</div></blockquote>
<p><strong>require_dimensions_n()</strong></p>
<blockquote>
<div><p>Return type: <code class="docutils literal notranslate"><span class="pre">int</span></code></p>
<p>Arguments:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span> <span class="pre">ary</span></code>, a NumPy array.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">int*</span> <span class="pre">exact_dimensions</span></code>, an array of integers representing
acceptable numbers of dimensions.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">n</span></code>, the length of <code class="docutils literal notranslate"><span class="pre">exact_dimensions</span></code>.</p></li>
</ul>
<p>Require <code class="docutils literal notranslate"><span class="pre">ary</span></code> to have one of a list of specified number of
dimensions.  If the array has one of the specified number of
dimensions, return 1.  Otherwise, set the Python error string
and return 0.</p>
</div></blockquote>
<p><strong>require_size()</strong></p>
<blockquote>
<div><p>Return type: <code class="docutils literal notranslate"><span class="pre">int</span></code></p>
<p>Arguments:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span> <span class="pre">ary</span></code>, a NumPy array.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">npy_int*</span> <span class="pre">size</span></code>, an array representing the desired lengths of
each dimension.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">n</span></code>, the length of <code class="docutils literal notranslate"><span class="pre">size</span></code>.</p></li>
</ul>
<p>Require <code class="docutils literal notranslate"><span class="pre">ary</span></code> to have a specified shape.  If the array has the
specified shape, return 1.  Otherwise, set the Python error
string and return 0.</p>
</div></blockquote>
<p><strong>require_fortran()</strong></p>
<blockquote>
<div><p>Return type: <code class="docutils literal notranslate"><span class="pre">int</span></code></p>
<p>Arguments:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span> <span class="pre">ary</span></code>, a NumPy array.</p></li>
</ul>
<p>Require the given <code class="docutils literal notranslate"><span class="pre">PyArrayObject</span></code> to to be Fortran ordered.  If
the <code class="docutils literal notranslate"><span class="pre">PyArrayObject</span></code> is already Fortran ordered, do nothing.
Else, set the Fortran ordering flag and recompute the strides.</p>
</div></blockquote>
</div></blockquote>
</div>
</div>
<div class="section" id="beyond-the-provided-typemaps">
<h2>Beyond the Provided Typemaps<a class="headerlink" href="#beyond-the-provided-typemaps" title="Permalink to this headline">¶</a></h2>
<p>There are many C or C++ array/NumPy array situations not covered by
a simple <code class="docutils literal notranslate"><span class="pre">%include</span> <span class="pre">&quot;numpy.i&quot;</span></code> and subsequent <code class="docutils literal notranslate"><span class="pre">%apply</span></code> directives.</p>
<div class="section" id="a-common-example">
<h3>A Common Example<a class="headerlink" href="#a-common-example" title="Permalink to this headline">¶</a></h3>
<p>Consider a reasonable prototype for a dot product function:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">double</span> <span class="n">dot</span><span class="p">(</span><span class="nb">int</span> <span class="nb">len</span><span class="p">,</span> <span class="n">double</span><span class="o">*</span> <span class="n">vec1</span><span class="p">,</span> <span class="n">double</span><span class="o">*</span> <span class="n">vec2</span><span class="p">);</span>
</pre></div>
</div>
<p>The Python interface that we want is:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">dot</span><span class="p">(</span><span class="n">vec1</span><span class="p">,</span> <span class="n">vec2</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    dot(PyObject,PyObject) -&gt; double</span>
<span class="sd">    &quot;&quot;&quot;</span>
</pre></div>
</div>
<p>The problem here is that there is one dimension argument and two array
arguments, and our typemaps are set up for dimensions that apply to a
single array (in fact, <a class="reference external" href="http://www.swig.org">SWIG</a> does not provide a mechanism for
associating <code class="docutils literal notranslate"><span class="pre">len</span></code> with <code class="docutils literal notranslate"><span class="pre">vec2</span></code> that takes two Python input
arguments).  The recommended solution is the following:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>%apply (int DIM1, double* IN_ARRAY1) {(int len1, double* vec1),
                                      (int len2, double* vec2)}
%rename (dot) my_dot;
%exception my_dot {
    $action
    if (PyErr_Occurred()) SWIG_fail;
}
%inline %{
double my_dot(int len1, double* vec1, int len2, double* vec2) {
    if (len1 != len2) {
        PyErr_Format(PyExc_ValueError,
                     &quot;Arrays of lengths (%d,%d) given&quot;,
                     len1, len2);
        return 0.0;
    }
    return dot(len1, vec1, vec2);
}
%}
</pre></div>
</div>
<p>If the header file that contains the prototype for <code class="docutils literal notranslate"><span class="pre">double</span> <span class="pre">dot()</span></code>
also contains other prototypes that you want to wrap, so that you need
to <code class="docutils literal notranslate"><span class="pre">%include</span></code> this header file, then you will also need a <code class="docutils literal notranslate"><span class="pre">%ignore</span>
<span class="pre">dot;</span></code> directive, placed after the <code class="docutils literal notranslate"><span class="pre">%rename</span></code> and before the
<code class="docutils literal notranslate"><span class="pre">%include</span></code> directives.  Or, if the function in question is a class
method, you will want to use <code class="docutils literal notranslate"><span class="pre">%extend</span></code> rather than <code class="docutils literal notranslate"><span class="pre">%inline</span></code> in
addition to <code class="docutils literal notranslate"><span class="pre">%ignore</span></code>.</p>
<p><strong>A note on error handling:</strong> Note that <code class="docutils literal notranslate"><span class="pre">my_dot</span></code> returns a
<code class="docutils literal notranslate"><span class="pre">double</span></code> but that it can also raise a Python error.  The
resulting wrapper function will return a Python float
representation of 0.0 when the vector lengths do not match.  Since
this is not <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, the Python interpreter will not know to check
for an error.  For this reason, we add the <code class="docutils literal notranslate"><span class="pre">%exception</span></code> directive
above for <code class="docutils literal notranslate"><span class="pre">my_dot</span></code> to get the behavior we want (note that
<code class="docutils literal notranslate"><span class="pre">$action</span></code> is a macro that gets expanded to a valid call to
<code class="docutils literal notranslate"><span class="pre">my_dot</span></code>).  In general, you will probably want to write a <a class="reference external" href="http://www.swig.org">SWIG</a>
macro to perform this task.</p>
</div>
<div class="section" id="other-situations">
<h3>Other Situations<a class="headerlink" href="#other-situations" title="Permalink to this headline">¶</a></h3>
<p>There are other wrapping situations in which <code class="docutils literal notranslate"><span class="pre">numpy.i</span></code> may be
helpful when you encounter them.</p>
<blockquote>
<div><ul>
<li><p>In some situations, it is possible that you could use the
<code class="docutils literal notranslate"><span class="pre">%numpy_typemaps</span></code> macro to implement typemaps for your own
types.  See the <a class="reference internal" href="#other-common-types-bool">Other Common Types: bool</a> or <a class="reference internal" href="#other-common-types-complex">Other Common
Types: complex</a> sections for examples.  Another situation is if
your dimensions are of a type other than <code class="docutils literal notranslate"><span class="pre">int</span></code> (say <code class="docutils literal notranslate"><span class="pre">long</span></code> for
example):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span><span class="n">numpy_typemaps</span><span class="p">(</span><span class="n">double</span><span class="p">,</span> <span class="n">NPY_DOUBLE</span><span class="p">,</span> <span class="n">long</span><span class="p">)</span>
</pre></div>
</div>
</li>
<li><p>You can use the code in <code class="docutils literal notranslate"><span class="pre">numpy.i</span></code> to write your own typemaps.
For example, if you had a five-dimensional array as a function
argument, you could cut-and-paste the appropriate four-dimensional
typemaps into your interface file.  The modifications for the
fourth dimension would be trivial.</p></li>
<li><p>Sometimes, the best approach is to use the <code class="docutils literal notranslate"><span class="pre">%extend</span></code> directive
to define new methods for your classes (or overload existing ones)
that take a <code class="docutils literal notranslate"><span class="pre">PyObject*</span></code> (that either is or can be converted to a
<code class="docutils literal notranslate"><span class="pre">PyArrayObject*</span></code>) instead of a pointer to a buffer.  In this
case, the helper routines in <code class="docutils literal notranslate"><span class="pre">numpy.i</span></code> can be very useful.</p></li>
<li><p>Writing typemaps can be a bit nonintuitive.  If you have specific
questions about writing <a class="reference external" href="http://www.swig.org">SWIG</a> typemaps for NumPy, the
developers of <code class="docutils literal notranslate"><span class="pre">numpy.i</span></code> do monitor the
<a class="reference external" href="mailto:Numpy-discussion&#37;&#52;&#48;python&#46;org">Numpy-discussion</a> and
<a class="reference external" href="mailto:Swig-user&#37;&#52;&#48;lists&#46;sourceforge&#46;net">Swig-user</a> mail lists.</p></li>
</ul>
</div></blockquote>
</div>
<div class="section" id="a-final-note">
<h3>A Final Note<a class="headerlink" href="#a-final-note" title="Permalink to this headline">¶</a></h3>
<p>When you use the <code class="docutils literal notranslate"><span class="pre">%apply</span></code> directive, as is usually necessary to use
<code class="docutils literal notranslate"><span class="pre">numpy.i</span></code>, it will remain in effect until you tell <a class="reference external" href="http://www.swig.org">SWIG</a> that it
shouldn’t be.  If the arguments to the functions or methods that you
are wrapping have common names, such as <code class="docutils literal notranslate"><span class="pre">length</span></code> or <code class="docutils literal notranslate"><span class="pre">vector</span></code>,
these typemaps may get applied in situations you do not expect or
want.  Therefore, it is always a good idea to add a <code class="docutils literal notranslate"><span class="pre">%clear</span></code>
directive after you are done with a specific typemap:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span><span class="n">apply</span> <span class="p">(</span><span class="n">double</span><span class="o">*</span> <span class="n">IN_ARRAY1</span><span class="p">,</span> <span class="nb">int</span> <span class="n">DIM1</span><span class="p">)</span> <span class="p">{(</span><span class="n">double</span><span class="o">*</span> <span class="n">vector</span><span class="p">,</span> <span class="nb">int</span> <span class="n">length</span><span class="p">)}</span>
<span class="o">%</span><span class="n">include</span> <span class="s2">&quot;my_header.h&quot;</span>
<span class="o">%</span><span class="n">clear</span> <span class="p">(</span><span class="n">double</span><span class="o">*</span> <span class="n">vector</span><span class="p">,</span> <span class="nb">int</span> <span class="n">length</span><span class="p">);</span>
</pre></div>
</div>
<p>In general, you should target these typemap signatures specifically
where you want them, and then clear them after you are done.</p>
</div>
</div>
<div class="section" id="summary">
<h2>Summary<a class="headerlink" href="#summary" title="Permalink to this headline">¶</a></h2>
<p>Out of the box, <code class="docutils literal notranslate"><span class="pre">numpy.i</span></code> provides typemaps that support conversion
between NumPy arrays and C arrays:</p>
<blockquote>
<div><ul class="simple">
<li><p>That can be one of 12 different scalar types: <code class="docutils literal notranslate"><span class="pre">signed</span> <span class="pre">char</span></code>,
<code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">char</span></code>, <code class="docutils literal notranslate"><span class="pre">short</span></code>, <code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">short</span></code>, <code class="docutils literal notranslate"><span class="pre">int</span></code>,
<code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">int</span></code>, <code class="docutils literal notranslate"><span class="pre">long</span></code>, <code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span></code>, <code class="docutils literal notranslate"><span class="pre">long</span> <span class="pre">long</span></code>,
<code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></code>, <code class="docutils literal notranslate"><span class="pre">float</span></code> and <code class="docutils literal notranslate"><span class="pre">double</span></code>.</p></li>
<li><p>That support 74 different argument signatures for each data type,
including:</p>
<ul>
<li><p>One-dimensional, two-dimensional, three-dimensional and
four-dimensional arrays.</p></li>
<li><p>Input-only, in-place, argout, argoutview, and memory managed
argoutview behavior.</p></li>
<li><p>Hard-coded dimensions, data-buffer-then-dimensions
specification, and dimensions-then-data-buffer specification.</p></li>
<li><p>Both C-ordering (“last dimension fastest”) or Fortran-ordering
(“first dimension fastest”) support for 2D, 3D and 4D arrays.</p></li>
</ul>
</li>
</ul>
</div></blockquote>
<p>The <code class="docutils literal notranslate"><span class="pre">numpy.i</span></code> interface file also provides additional tools for
wrapper developers, including:</p>
<blockquote>
<div><ul class="simple">
<li><p>A <a class="reference external" href="http://www.swig.org">SWIG</a> macro (<code class="docutils literal notranslate"><span class="pre">%numpy_typemaps</span></code>) with three arguments for
implementing the 74 argument signatures for the user’s choice of
(1) C data type, (2) NumPy data type (assuming they match), and
(3) dimension type.</p></li>
<li><p>Fourteen C macros and fifteen C functions that can be used to
write specialized typemaps, extensions, or inlined functions that
handle cases not covered by the provided typemaps.  Note that the
macros and functions are coded specifically to work with the NumPy
C/API regardless of NumPy version number, both before and after
the deprecation of some aspects of the API after version 1.6.</p></li>
</ul>
</div></blockquote>
</div>
</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>